home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / uw_1.exe / UW_HELP6.HLP < prev    next >
Text File  |  1992-11-13  |  22KB  |  512 lines
  1. `co(4,7);──────────────────────────── /// Print Support ───────────────────────────────`co();
  2.  
  3.                                `keyword(Introduction,/// Introduction);
  4.                            `keyword(Key Structure Elements,/// Key Structure Elements);
  5.  
  6.  ┌──────────────────────────────────────────────────────────────────────────┐    
  7.  │               `keyword(init_printer,/// init_printer);                `keyword(end_printer,/// end_printer);                    │
  8.  │               `keyword(print_char,/// print_char);                  `keyword(print_data,/// print_data);                     │
  9.  │               `keyword(print_eol,/// print_eol);                   `keyword(print_file,/// print_file);                     │
  10.  │               `keyword(print_screen,/// print_screen);                `keyword(print_str,/// print_str);                      │
  11.  │               `keyword(print_window,/// print_window);                `keyword(realloc_printer,/// realloc_printer);                │
  12.  │               `keyword(set_prt_xlat,/// set_prt_xlat);                `keyword(print_in_bkgrnd,/// print_in_bkgrnd);                │
  13.  └──────────────────────────────────────────────────────────────────────────┘
  14.  
  15. `co(4,7);─────────────────────────── /// Introduction ─────────────────────────────────`co();
  16.  
  17.       These routines are primarily designed for printing to a printer.
  18.     However, printing can be output to a DOS file or device (com1, lpt1,
  19.     tmp.dat, etc).  UltraWin can have as many as four print queues active and
  20.     printing concurrently!  The queuing routines are unique in the fact that
  21.     they can "dynamically" reallocate themselves and "grow" and "shrink" on the
  22.     fly without losing a single byte of data.  The reallocation routines take
  23.     advantage of the lightning fast movmem, as much out of convenience as
  24.     speed.  An 8Mhz 286 can queue 25,000 bytes worth of text strings in one
  25.     second, reallocating every 2048 bytes; really quite remarkable.  The
  26.     output is very fast.  Under normal operation, a "write" occurs on every
  27.     byte, resulting in ~1024 bytes per second (on the same machine).  Not many
  28.     printers can keep up with this speed!  Even greater speed is achieved by
  29.     using "block mode", where each write can output 512 bytes at a time.  This
  30.     is not done by default since outputting to a comm port at a slow baud rate
  31.     could hamper overall performance.
  32.  
  33. `color(RED,LIGHTGRAY);─────────────────────── /// Key Structure Elements ───────────────────────────`color();
  34.  
  35.       Several print structure elements are of importance.  These elements can
  36.     be modified directly for the desired effect.
  37.      
  38.     The `co(15,1);halt`co(); member controls output from the queue.  If 1, output stops
  39.   and the data in the queue remains unmodified.  If set to 0, output
  40.   continues.
  41.  
  42.     The `co(15,1);block_mode`co(); member controls the number of bytes output per
  43.   call to the function "print_in_bkgnd".  If 0, only one byte per call will
  44.     be output.  This is useful for communication devices or printers.  If
  45.     outputting to a file or laser printer, setting block mode to 1 will allow
  46.     up to 512 bytes to be output per call, thereby increasing performance.
  47.     This value is defined in UW.H.  Changing this value and recompiling
  48.     UW_PRINT.C will allow you to change the number of bytes sent per block.
  49.  
  50.         The `co(15,1);xlat`co(); and `co(15,1);xlat_flag`co(); control printer translation.  See `keyword(set_prt_xlat,/// set_prt_xlat);
  51.     for more details.
  52.  
  53. `co(10,1);/// init_printer`co();   `keyword(source,[UW_PRINT.C]~init_printer);
  54.       Initializes a printer queue.  Printer queues can be either ram-based or
  55.     disk-based. If ram-based, a queue can be no greater than 64k.  Disk-based
  56.     queues can be up to 2 gigabytes. (Though we have never actually tried this
  57.     size!).  If disk-based, the initial and maximum size should be set to the
  58.     same value, and a second filename is used as a disk buffer.  Be sure that
  59.     the isize and msize values are "long". If any error occurs (file cannot be
  60.     open, memory cannot be allocated,etc) a 0 will be returned.
  61.  
  62. Prototype:
  63.     int init_printer( char *fname, char *diskbuff, long isize,
  64.                                         long msize, PRINT *p );
  65.  
  66. Parameters:
  67. `co(11,1);    char  *fname`co();
  68.         A pointer to a string containing the filename/device to print to.
  69. `co(11,1);    char  *diskbuff`co();
  70.         A pointer to a string containing the filename/device to use as a disk
  71.     buffer.  This is NULL for ram-based queues.
  72. `co(11,1);    long  isize`co();
  73.         The initial size of the print queue. (Maximum 64k if ram based)
  74. `co(11,1);    long  msize`co();
  75.         The maximum size of the print queue. (Maximum 64k if ram based)
  76.         isize and msize should be set equal if using a disk based queue.
  77. `co(11,1);    PRINT *p`co();
  78.     A pointer to a print queue structure.   
  79.  
  80. Usage:
  81.     PRINT printer1, printer2;
  82.     ...
  83.     if( !init_printer("out1.prt", NULL, 2048L, 16384L, &printer1) )
  84.         wn_plst(0,0,"cannot initialize printer", wnp);
  85.     if( !init_printer("out2.prt", "disk.buf", 32768L, 32768L, &printer2) )
  86.         wn_plst(0,0,"cannot initialize printer", wnp);
  87.  
  88. `co(10,1);/// end_printer`co();   `keyword(source,[UW_PRINT.C]~end_printer);
  89.       Closes any files and frees any memory used by the print queue.  If
  90.     disk-based, the temporary disk file is left intact so that it will not
  91.     have to be recreated during the next program execution. You may delete
  92.     this file yourself if desired.
  93.  
  94. Prototype:
  95.     int end_printer( PRINT *p );
  96.  
  97. Parameters:
  98. `co(11,1);    PRINT *p`co();
  99.     A pointer to a print queue structure.   
  100.  
  101. Usage:
  102.     PRINT printer1;
  103.     ...
  104.     end_printer(&printer1);
  105.  
  106. `co(10,1);/// print_char`co();   `keyword(source,[UW_PRINT.C]~print_char);
  107.       Prints a single character.     A 0 is returned if an error occurs.
  108.  
  109. Prototype:
  110.     int print_char( uchar c, PRINT *p );
  111.  
  112. Parameters:
  113. `co(11,1);    uchar c`co();
  114.     A single byte to queue for printing.   
  115. `co(11,1);    PRINT *p`co();
  116.     A pointer to a print queue structure.   
  117.  
  118. Usage:
  119.     PRINT printer1;
  120.     ...
  121.     print_char('\r', &printer1);
  122.  
  123. `co(10,1);/// print_data`co();   `keyword(source,[UW_PRINT.C]~print_data);
  124.       Prints a block of data.  A 0 is returned if an error occurs.
  125.  
  126. Prototype:
  127.     int print_data( uchar *data, int cnt, PRINT *p );
  128.  
  129. Parameters:
  130. `co(11,1);    uchar *data`co();
  131.     A pointer to the data to queue for printing.   
  132. `co(11,1);    int   cnt`co();
  133.     The number of bytes to print.   
  134. `co(11,1);    PRINT *p`co();
  135.     A pointer to a print queue structure.   
  136.  
  137. Usage:
  138.     uchar data[132];
  139.     PRINT printer1;
  140.     ...
  141.     print_data(data, 132, &printer1);
  142.  
  143. `co(10,1);/// print_eol`co();   `keyword(source,[UW_PRINT.C]~print_eol);
  144.       Prints an end-of-line sequence.  The print structure contains two
  145.     variables, "cr_cnt" and "lf_cnt" that control this sequence.  For every
  146.     carriage return "cr_cnt", "lf_cnt" line feeds are printed.
  147.     
  148.         For instance, the simple case of cr_cnt = lf_cnt = 1 outputs \r\n  while
  149.     cr_cnt = 1, lf_cnt = 2 outputs \r\n\n.  A 0 is returned if an error
  150.     occurs.
  151.  
  152. Prototype:
  153.     int print_eol( PRINT *p );
  154.  
  155. Parameters:
  156. `co(11,1);    PRINT *p`co();
  157.     A pointer to a print queue structure.   
  158.  
  159. Usage:
  160.     PRINT printer1;
  161.     ...
  162.     print_eol(&printer1);
  163.  
  164. `co(10,1);/// print_file`co();   `keyword(source,[UW_PRINT.C]~print_file);
  165.       Prints an entire file.  The file is queued in "raw" format, no CR/LF
  166.     translation occurs.  Make sure that there is enough room in the queue to
  167.     hold the entire file.  A 0 is returned if an error occurs.
  168.  
  169. Prototype:
  170.     int print_file( char *fname, PRINT *p );
  171.  
  172. Parameters:
  173. `co(11,1);    char  *fname`co();
  174.         A pointer to a string containing the filename/device to print to.
  175. `co(11,1);    PRINT *p`co();
  176.     A pointer to a print queue structure.   
  177.  
  178. Usage:
  179.     PRINT printer1;
  180.     ...
  181.     print_file("uw_help6.hlp", &printer1);
  182.  
  183. `co(10,1);/// print_screen`co();   `keyword(source,[UW_PRINT.C]~print_screen);
  184.       Prints the contents of the entire screen.  A 0 is returned if an error
  185.     occurs.
  186.  
  187. Prototype:
  188.     int print_screen( PRINT *p );
  189.  
  190. Parameters:
  191. `co(11,1);    PRINT *p`co();
  192.     A pointer to a print queue structure.   
  193.  
  194. Usage:
  195.     PRINT printer1;
  196.     ...
  197.     print_screen(&printer1);
  198.  
  199. `co